// Copyright (C) ZHENG Zhong <heavyzheng nospam-at gmail D0T com>
//
// $Id: parser.hpp 318 2009-03-02 14:03:21Z heavyzheng $
//

#ifndef ZZHENG_XML_DOM_LIBXML2_PARSER_HPP_20080717__
#define ZZHENG_XML_DOM_LIBXML2_PARSER_HPP_20080717__

#include <zzheng/xml/config.hpp>
#include <zzheng/xml/dom/basic_node_ptr.hpp>

#include <zzheng/xml/dom/libxml2/base.hpp>
#include <zzheng/xml/dom/libxml2/document.hpp>
#include <zzheng/xml/dom/libxml2/libxml2_fwd.hpp>

#include <string>

namespace zzheng {
namespace xml {
namespace dom {
namespace libxml2_ {

    //! This class represents an XML DOM parser. A parser is used to parse an XML file or string
    //! and return the document object.
    class parser: private base {

    public:

        //! Default constructor.
        explicit parser();

        //! Destructor.
        ~parser();

        //! Parses an XML file to a document object. It is up to the user to free the document
        //! object. It is recommended that user use the RAII idiom and put the returned document
        //! into a smart pointer (std::auto_ptr or boost::shared_ptr).
        //! \param file_name  the name of the xml file to parse.
        //! \return a document object parsed from the file, never null.
        //! \throws dom_error  if fail to parse the XML file.
        document* parse_file(const std::string& file_name);

        //! Parses a memory block containing XML to a document object. It is up to the user to free
        //! the document object. It is recommended that user use the RAII idiom and put the
        //! returned document into a smart pointer (std::auto_ptr or boost::shared_ptr).
        //! \param str  the string containing XML to parse.
        //! \return a document object parsed from the string, never null.
        //! \throws dom_error  if fail to parse the XML string.
        document* parse_string(char const* str);

    private:

        //! Non-implemented copy constructor.
        parser(const parser&);

        //! Non-implemented copy assignment.
        parser& operator=(const parser&);

    }; // class parser

} // namespace zzheng::xml::dom::libxml2_
} // namespace zzheng::xml::dom
} // namespace zzheng::xml
} // namespace zzheng

#endif // ZZHENG_XML_DOM_LIBXML2_PARSER_HPP_20080717__



